Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Board catalog/hw feature v2 with line numbers #64

Open
wants to merge 24 commits into
base: xx
Choose a base branch
from

Conversation

kartben
Copy link
Owner

@kartben kartben commented Feb 25, 2025

No description provided.

Copy link

Warning

Gemini encountered an error creating the summary. You can try again by commenting /gemini summary.

@kartben
Copy link
Owner Author

kartben commented Feb 25, 2025

/gemini summary

Copy link

Summary of Changes

This pull request focuses on enhancing the board catalog and hardware feature documentation within the Zephyr project. The primary goal is to improve the representation and accessibility of hardware feature information for different boards. This includes adding a legend to the hardware features table, providing location information (on-chip vs. on-board), displaying the number of instances for each feature (enabled and disabled), and linking directly to the relevant Devicetree binding documentation and source files with line numbers. Additionally, CSS and JS files are added to support the new board documentation features.

Highlights

  • Hardware Features Table Legend: A legend is added to the hardware features table to explain the meaning of different indicators, such as 'on-chip', 'on-board', and the count of enabled/disabled instances.
  • Location Information: The location of each hardware feature (whether it's on-chip or on-board) is now displayed in the table.
  • Instance Counts and Links: The number of enabled and disabled instances of each feature are shown, with links to the corresponding source files in the Devicetree.
  • Devicetree Binding Links: Links to the Devicetree binding documentation are added for each compatible string.
  • Line Numbers in Links: The zephyr_file role now supports linking to specific lines in files.

Changelog

Click here to see the changelog
  • doc/Makefile
    • Modified the html-fast target to disable HW_FEATURES_TURBO_MODE.
  • doc/_extensions/zephyr/domain/init.py
    • Added logic to flag boards as having documentation pages.
    • Implemented the table legend for hardware features.
    • Added columns for 'Location' in the hardware features table.
    • Added count indicators for enabled and disabled feature instances, with links to source files.
    • Added links to Devicetree binding documentation.
    • Added a 'has_board' flag to track documents containing board-specific directives.
    • Modified the table to include the location of the hardware feature.
  • doc/_extensions/zephyr/domain/static/css/board.css
    • Added CSS styles for the board overview card, legend, hardware features table, location chips, and status indicators.
  • doc/_extensions/zephyr/domain/static/js/board.js
    • Added an empty JS file for board-specific JavaScript functionality.
  • doc/_extensions/zephyr/link-roles.py
    • Modified the zephyr_file role to support linking to specific lines in files.
  • doc/_scripts/gen_boards_catalog.py
    • Modified the script to gather information about enabled and disabled nodes, their locations, and descriptions.
    • Modified the script to generate hardware features for specific boards.
  • doc/_static/css/custom.css
    • Removed duplicate CSS styles that were moved to board.css.
  • scripts/dts/python-devicetree/src/devicetree/dtlib.py
    • Added filename and lineno attributes to the Node and Property classes.
    • Modified the Node constructor to accept filename and lineno.
    • Modified the DT class to track filename and lineno during parsing.
    • Modified the deepcopy method to copy filename and lineno.
  • scripts/dts/python-devicetree/src/devicetree/edtlib.py
    • Added filename and lineno properties to the Node class.
  • scripts/dts/python-devicetree/tests/test_dtlib.py
    • Added a test case to verify that filename and lineno are correctly tracked for nodes and properties.

Activity

  • gemini-code-assist[bot] encountered an error creating the summary and asked to try again.
  • kartben requested a summary again.

@kartben
Copy link
Owner Author

kartben commented Feb 25, 2025

/Gemini review

@kartben
Copy link
Owner Author

kartben commented Feb 25, 2025

/gemini review

Copy link

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

The pull request introduces several enhancements to the Zephyr documentation build process and board catalog generation. The addition of board-specific CSS and JavaScript files, along with modifications to the device tree parsing and display, improves the overall user experience. However, there are a few areas that could benefit from further refinement, particularly in the Makefile and the device tree parsing logic.

Summary of Findings

  • Makefile Configuration: The change in the Makefile to set HW_FEATURES_TURBO_MODE=0 in the html-fast target might have unintended consequences. It's important to verify that this change doesn't negatively impact the build process or the generated documentation.
  • Device Tree Parsing: The modifications to the device tree parsing logic in gen_boards_catalog.py introduce new features and data extraction. It's crucial to ensure that these changes are thoroughly tested to prevent errors or unexpected behavior.
  • CSS and JavaScript Inclusion: The addition of board-specific CSS and JavaScript files in __init__.py enhances the documentation's presentation and functionality. However, it's important to ensure that these files are properly maintained and updated to avoid compatibility issues.

Assessment

The pull request introduces several enhancements to the Zephyr documentation build process and board catalog generation. The addition of board-specific CSS and JavaScript files, along with modifications to the device tree parsing and display, improves the overall user experience. However, there are a few areas that could benefit from further refinement, particularly in the Makefile and the device tree parsing logic. I would recommend addressing these comments before requesting a review from someone else, but feel free to request another review from Gemini via /gemini review when you have addressed these comments and I'll take another look! Users should have others review and approve this code before merging.

Copy link

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

The pull request introduces several enhancements to the Zephyr documentation build process and board catalog generation. The changes include modifications to the Makefile, updates to the Zephyr domain for handling board-specific documentation, and additions to the device tree parsing logic. While the changes generally improve the documentation and board catalog generation, there are a few areas that could benefit from further refinement.

Summary of Findings

  • Makefile Optimization: The change in the Makefile modifies the HW_FEATURES_TURBO_MODE variable. It's important to verify the implications of this change on the build process and ensure it aligns with the intended behavior.
  • Board Documentation: The addition of board-specific CSS and JavaScript files suggests a new feature for board documentation. It's crucial to ensure that these files are correctly integrated and that the new feature functions as expected.
  • Device Tree Parsing: The updates to the device tree parsing logic include adding filename and line number tracking for nodes and properties. This enhancement improves the debugging and maintainability of the device tree representation.
  • Feature Flagging: The addition of the has_board flag in the Zephyr domain data indicates a new way to track board-specific documentation. It's important to ensure that this flag is used consistently and correctly throughout the documentation generation process.

Assessment

The pull request introduces several enhancements to the Zephyr documentation build process and board catalog generation. The changes include modifications to the Makefile, updates to the Zephyr domain for handling board-specific documentation, and additions to the device tree parsing logic. While the changes generally improve the documentation and board catalog generation, there are a few areas that could benefit from further refinement. I recommend addressing the comments before merging, and also ensuring that another reviewer approves this code before merging.

@kartben kartben force-pushed the board_catalog/hw_feature_v2_with_line_numbers branch 12 times, most recently from 4d4bffe to 6287aa8 Compare February 28, 2025 09:12
@kartben
Copy link
Owner Author

kartben commented Feb 28, 2025

/gemini review

Copy link

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.

@kartben kartben force-pushed the board_catalog/hw_feature_v2_with_line_numbers branch from 6287aa8 to cae6dc0 Compare February 28, 2025 10:16
Mattemagikern and others added 8 commits February 28, 2025 14:51
The day alarm was not being set correctly. The day alarm should be set
using the WADA bit in the control register. This patch fixes the issue
by setting the WADA bit in the control register when setting the day alarm.

Signed-off-by: Måns Ansgariusson <[email protected]>
We need to track the self-powered status of the device independently of
the D6 bit in the bmAttributes value of the configuration descriptor
because the Get Status request about the self-powered status is valid in
address state and we support multiple configurations.

Signed-off-by: Johann Fischer <[email protected]>
Add a notice to the 4.1 release notes that CONFIG_PIPES k_pipe
implementation is deprecated from 4.1.

Signed-off-by: Måns Ansgariusson <[email protected]>
Fixes a wrongly defined Kconfig

Signed-off-by: Jamie McCrae <[email protected]>
This updates the documentation of all the UP boards to use
the new `zephyr:board::` directive.

Signed-off-by: Benjamin Cabé <[email protected]>
This updates the documentation of all the lowRISC boards to use
the new `zephyr:board::` directive.

Signed-off-by: Benjamin Cabé <[email protected]>
This updates the documentation of all the Seagate boards to use
the new `zephyr:board::` directive.

Signed-off-by: Benjamin Cabé <[email protected]>
This updates the documentation of all the EnjoyDigital boards to use
the new `zephyr:board::` directive.

Signed-off-by: Benjamin Cabé <[email protected]>
kartben and others added 16 commits February 28, 2025 14:52
This updates the documentation of all the Cypress boards to use
the new `zephyr:board::` directive.

Signed-off-by: Benjamin Cabé <[email protected]>
Title is redundant with the one the zephyr:board directive
automatically adds.

Signed-off-by: Benjamin Cabé <[email protected]>
This updates the documentation of all the ENE Technology boards to use
the new `zephyr:board::` directive.

Signed-off-by: Benjamin Cabé <[email protected]>
This updates the documentation of all the ITE Tech boards to use
the new `zephyr:board::` directive.

Signed-off-by: Benjamin Cabé <[email protected]>
Activating the Python environment on Windows can be done in a regular
command line prompt, or in powershell. But the activation script is
different.
Add a code tabs to include the powershell alternative.

Signed-off-by: Pieter De Gendt <[email protected]>
Replace conditional `ARG_UNUSED` with `__maybe_unused`. This is recommended
by coding style:
https://kernel.org/doc/html/latest/process/coding-style.html#conditional-compilation

Signed-off-by: Jeppe Odgaard <[email protected]>
Fix BT_CTLR_LOW_LAT_ULL dependency after changes in
commit 5119896 ("Bluetooth: Controller: Fix
BT_CTLR_LOW_LAT_ULL conditional code").

BT_CTLR_LOW_LAT_ULL is independent of BT_CTLR_LOW_LAT, where
the later prevents any ULL execution inside a radio event.

Signed-off-by: Vinayak Kariappa Chettimada <[email protected]>
Setup logging per process to fix issue on both mac and windows where
handlers are not available to the processes.

Fixes zephyrproject-rtos#86237

Signed-off-by: Anas Nashif <[email protected]>
Init function uses undefined cfg variable causing compilation error.

Signed-off-by: Jan Kowalewski <[email protected]>
Fix active mode extended scanning assert raised when calling
radio_tmr_start_us() due to stale radio_tmr_end_get() value.
Active mode extended scanning did not drop reception of
ADV_EXT_IND PDU when setup to receive ADV_SCAN_RSP PDUs.

Signed-off-by: Vinayak Kariappa Chettimada <[email protected]>
Fix single timer use end time capture from being disabled
as end time and timer clear use the same PPI.

Signed-off-by: Vinayak Kariappa Chettimada <[email protected]>
Fix end time capture be on radio event end irrespective of
direction finding support. Let the timer clear use radio
end or radio phy end, for no direction finding or direction
finding support, respectively.

Signed-off-by: Vinayak Kariappa Chettimada <[email protected]>
Rename the single timer clear event define name based on
direction finding support.

Signed-off-by: Vinayak Kariappa Chettimada <[email protected]>
Fix use of single timer software tIFS switching to support
direction finding.

Signed-off-by: Vinayak Kariappa Chettimada <[email protected]>
Use raw HTML as there's no point in having lots of docutils
boilerplate for what's effectively static content

Signed-off-by: Benjamin Cabé <[email protected]>
Update the gen_board_catalog.py logic to also capture lineno for
each devicetree node. Use that info in the supported hardware list to
create clickable elements that directly take the user to the
corresponding line in the devicetree file on Github.

Signed-off-by: Benjamin Cabé <[email protected]>
@kartben kartben force-pushed the board_catalog/hw_feature_v2_with_line_numbers branch from cae6dc0 to 4f77244 Compare February 28, 2025 14:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

8 participants